.TH JPNEVULATOR "1" "July 2020" "jpnevulator 2.3.6" "User Commands"
.SH NAME
jpnevulator \- Just another serial sniffer
.SH SYNOPSIS
.B jpnevulator
[\fIOPTION\fR]... <\fIFILE\fR>
.SH DESCRIPTION
.PP
jpnevulator is a handy serial sniffer. You can use it to send data on
a serial device too. You can read or write from/to one or more serial
devices at the same time.
.PP
In write (\-\-write) mode data to be sent on the serial device(s) is
read from a file or stdin in base (\-\-base) defined notation. Data
is sent on the serial device(s) line by line.
.PP
In read (\-\-read) mode data to be read from the serial device(s) is
written to a file or stdout in base (\-\-base) defined notation. Skim
through the options for several enhancements in the output. It's even
possible to pass(\-\-pass) on the data between the several serial devices.
.PP
Mandatory arguments to long options are mandatory for short options too.
.PP
Generic options:
.TP
\fB\-B\fR, \fB\-\-base\fR=\fIBASE\fR
Specify the base unit of read/write bytes. Currently only 2=binary and 16=hexadecimal
are supported. The default base unit is hexadecimal.

Selecting hexadecimal as the base unit, the input format is FD or 0xFD. Of
course all input is treated case-insensitive. Spaces may or may not be included
in the input. So DEADBEEF is exactly the same as DE AD   BE  EF.

Selecting binary as the base unit, the input format is 01000010. Spaces may or
may not be included in the input. So 01000010111 is exactely the same as
01000010 111. Yes, that's right! It's perfectly fine to write less than 8 bits,
excluding the leading zeros. Please understand if doing so, spaces are needed
to separate the individual bytes in this case, but that's obvious. If no spaces
are used, the parses reads the first 8 bits before it continues with the next, as
shown in the example above.
.TP
\fB\-l\fR, \fB\-\-alias\-separator\fR
Use the given string as the alias separator. See \-\-tty for more information.
.TP
\fB\-f\fR, \fB\-\-file\fR=\fINAME\fR
In write mode read the contents of the file given and send them on the serial
device(s) and in read mode write the contents of the serial device(s) to the
file given.
.TP
\fB\-h\fR, \fB\-\-help\fR
Shows a brief list of options.
.TP
\fB\-o\fR, \fB\-\-count\fR=\fIBYTES\fR
Exit after reading / writing the given amount of bytes.
.TP
\fB\-r\fR, \fB\-\-read\fR
Put the program in read mode. This way you read the data from the given
serial device(s) and write it to the file given or stdout if none given.
See the read options section for more read specific options.
.TP
\fB\-t\fR, \fB\-\-tty\fR=\fINAME:ALIAS\fR
The serial device to read from or write to. Use multiple times to read/write
from/to more than one serial device(s). For handy reference you can also
separate an alias from the tty name with a collon ':'. If a collon is for
some strange reason part of your device name, you can use the \-\-alias\-separator
option to specify another separation string. If an alias is given it will be
used as the name of the serial device.
.TP
\fB\-v\fR, \fB\-\-version\fR
Output the version information, a small GPL notice and exit.
.TP
\fB\-w\fR, \fB\-\-write\fR
Put the program in write mode. This way you read data from a given file or
stdin if none given and write it to the serial device(s) given. See the write
options section for more write specific options.
.PP
Read options:
.TP
\fB\-a\fR, \fB\-\-ascii\fR
Besides the normal output of the data, also display an extra column with the data
in the ASCII representation. Non printable characters are displayed as a dot '.'.
The ASCII data is displayed after the normal data.
.TP
\fB\-b\fR, \fB\-\-byte\-count\fR
Besides the normal output also display an extra column with the current
index number of the byte in the output. These numbers are displayed in front
of the normal output. When readin from multiple serial devices at the same
time the index number will increase per serial device.
.TP
\fB\-C\fR, \fB\-\-control\fR
Monitor modem control bits (line enable, data terminal ready, request to send,
secondary TXD, secondary RXD, clear to send, carrier detect, ring and data
set ready) too and notify changes. Use the \-\-control\-poll option to specify
how often to poll for the bits.
.TP
\fB\-D\fR, \fB\-\-control\-poll\fR=\fIMICROSECONDS\fR
The control poll is the amount of microseconds to wait in between two checks
of the modem control bits if nothing else is happening.
.TP
\fB\-P\fR, \fB\-\-pass\fR
This one passes all the data between the serial devices. Handy if you want to
put your serial sniffer in between the serial devices you want to sniff.
.TP
\fB\-q\fR, \fB\-\-pty\fR=\fI:ALIAS\fR
The pseudo-terminal device to read from. Use multiple times to read from more
than one pseudo-terminal device(s). For handy reference you can also use an
alias to name the pty. Make sure it starts with a collon ':'. Use the
\-\-alias\-separator option if you for some reason don't like to use a collon.
If an alias is given it will be used as the name of the pseudo-terminal device.
.TP
\fB\-e\fR, \fB\-\-timing\-delta\fR=\fIMICROSECONDS\fR
The timing delta is the amount of microseconds between two bytes that the latter
is considered to be part of a new package. The default is 100 milliseconds. Use
this option in conjunction with the \-\-timing\-print option.
.TP
\fB\-g\fR, \fB\-\-timing\-print\fR
Print a line of timing information before every continues stream of bytes. When
multiple serial devices are given also print the name or alias of the device
where the data is coming from.
.TP
\fB\-i\fR, \fB\-\-width\fR=\fIWIDTH\fR
The number of bytes to display on one line. The default is 16.
.TP
\fB\-A\fR, \fB\-\-append\fR
Append to the output file instead of overwriting. The default is to overwrite.
.TP
\fB\-S\fR, \fB\-\-append\-separator\fR
Use the given string as the append separator. The string is processed and
the '\\n' sequence transforms into a real newline. So far no other sequences
do anything special. The default is a single newline character.
.PP
Write options:
.TP
\fB\-c\fR, \fB\-\-checksum\fR
Append a single checksum byte to the line of data written to the serial
device(s) chosen. This checksum is a simple modulo 256 addition of all input
bytes on a line.
.TP
\fB\-z\fR, \fB\-\-crc8\fR=\fIPOLY\fR
Append a crc8 checksum to the line of data written to the serial device(s) chosen.
Use the optionally given poly as the polynomial. Specify the polynomial as hexadecimal
value, as in 0x07 (the default).
.TP
\fB\-y\fR, \fB\-\-crc16\fR=\fIPOLY\fR
Append a crc16 checksum to the line of data written to the serial device(s) chosen.
Use the optionally given poly as the polynomial. Specify the polynomial as hexadecimal
value, as in 0xA001 (the default).
.TP
\fB\-k\fR, \fB\-\-delay\-byte\fR=\fIMICROSECONDS\fR
This delay is an optional amount of microseconds to wait in between every input
byte is sent on the serial device(s).
.TP
\fB\-d\fR, \fB\-\-delay\-line\fR=\fIMICROSECONDS\fR
This delay is an optional amount of microseconds to wait in between every input
line is sent on the serial device(s).
.TP
\fB\-j\fR, \fB\-\-fuck\-up\fR
This is the special fuck up option. When the calculation of a checksum is chosen
(see checksum and crc* options) the checksum will be crippled on purpose. Carefully
named after the special Jan Arie de Bruin 'fuck up crc' button.
.TP
\fB\-n\fR, \fB\-\-no\-send\fR
Do not actually send the bytes on the serial device(s). Rather pointless, but seemed
one day long ago to be a rather handy feature.
.TP
\fB\-p\fR, \fB\-\-print\fR
Besided sending the data on the serial device(s) also write the data to stdout.
.TP
\fB\-s\fR, \fB\-\-size\fR=\fISIZE\fR
The maximum number of bytes per line to send on the serial device(s). The default
is 22, coming from back in the Cham2 days of the program.
.SH DIAGNOSTICS
Normally, exit status is 0 if the program did run with no problem whatsoever. If
the exit status is not equal to 0 an error message is printed on stderr which should
help you solve the problem.
.SH BUGS
.PP
\fBOrder of bytes broke when reading several tty devices at once\fR
.PP
The display of incoming bytes can be broke if you use multiple tty devices to
read from. At the moment I do not have a solution for this problem. Since I use
select() to watch the several tty devices and after the select() I have to
read() them one by one, I can not completely 100% display which bytes came after
which on different tty devices. Take the example below:
.PP
.RS
.nf
.sp .5
$ jpnevulator \-\-ascii \-\-timing\-print \-\-tty /dev/ttyS0 \-\-tty /dev/ttyUSB0 \-\-read
2006-05-30 13:23:49.461075: /dev/ttyS0
00 00 05 3B 0D 00 00 05                         ...;....
2006-05-30 13:23:49.461113: /dev/ttyUSB0
00 05 3B 0D 00 00 05 3B 0D                      ..;....;.
2006-05-30 13:23:49.473074: /dev/ttyS0
3B 0D 00 00 05 3B 0D                            ;....;.
2006-05-30 13:23:49.473105: /dev/ttyUSB0
00 12 05 06 39 00 12 05 06 39 1F 00 22 80 00 0E ....9....9.."...
$
.sp .5
.fi
.RE
.PP
And now see the order in which things really got sent on the line:
.PP
.RS
.nf
.sp .5
/dev/ttyS0:
00 00 05 3B 0D
/dev/ttyUSB0:
00 00 05 3B 0D
/dev/ttyS0:
00 00 05 3B 0D
/dev/ttyUSB0:
00 00 05 3B 0D
/dev/ttyS0:
00 00 05 3B 0D
/dev/ttyUSB0:
00 00 05 3B 0D 00 12 05 06 39 00 12 05 06 39 ...
.sp .5
.fi
.RE
.PP
As you can see /dev/ttyUSB0 receives the echo of all things sent by /dev/ttyS0.
This is exactly what happens. But since there does exist a small time between
the select() who is happy expressing something is available and the read() who
does get the available data, some extra data will be available. I have no idea
on how I can use high level system call like select() and read() and be still
able to put the bytes in the correct order. Anyone an idea?
.SH AUTHOR
Written by Freddy Spierenburg.
.SH "REPORTING BUGS"
Report bugs to <freddy@snarl.nl>.
.SH COPYRIGHT
Copyright \(co 2006-2020 Freddy Spierenburg
